DeepWiki

05.c - Automation-Scripts

Relevant source files

This page documents the bash automation scripts that listen for ntfy notifications and automatically clone customer repositories into private mirrors in the owner's GitHub account. The scripts serve as the execution layer of the automation pipeline, consuming events from the ntfy message broker and orchestrating git operations.

For information about the ntfy integration and notification payload format, see 5.1. For the conceptual overview of the cloning pipeline, see 5.2.

The codebase includes two script files with identical functionality:

Script FilePurposeLocation
ntfy-godeep-automation.shPrimary automation script for local executionscripts/ntfy-godeep-automation.sh L1-L152
ntfy-godeep-automation-remote.shIdentical copy intended for remote deployment scenariosscripts/ntfy-godeep-automation-remote.sh L1-L152

Both scripts contain identical code and can be used interchangeably. The separate files suggest a deployment strategy where one script runs on the owner's local machine while another could run on a remote server, but the implementation is identical.

Sources: scripts/ntfy-godeep-automation.sh L1-L152

scripts/ntfy-godeep-automation-remote.sh L1-L152

The scripts define three critical configuration constants at the top:

TOPIC="topic-XXXXXXXX"ADMIN_URL="https://www.godeep.wiki/api/admin/generate-token"CLONE_DIR="$HOME/godeep-clones"
VariablePurposeDefault Value
TOPICntfy.sh topic name for subscriptiontopic-XXXXXXXX
ADMIN_URLAPI endpoint for token generationhttps://www.godeep.wiki/api/admin/generate-token
CLONE_DIRLocal directory for repository clones~/godeep-clones

The scripts also dynamically determine their location and project root:

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"

This allows the script to locate the .env file regardless of the current working directory when executed.

Sources: scripts/ntfy-godeep-automation.sh L6-L13

The script reads ADMIN_PASSWORD from the .env file located in the project root. This extraction happens at startup with validation:

Password Extraction Flow

The extraction command uses shell utilities to parse the .env file:

ADMIN_PASSWORD=$(grep "^ADMIN_PASSWORD=" "$ENV_FILE" | cut -d '=' -f2- | tr -d '"' | tr -d "'")

This command:

  1. Uses grep to find lines starting with ADMIN_PASSWORD=
  2. Uses cut to extract everything after the = sign
  3. Uses tr to remove surrounding quotes (both single and double)

Sources: scripts/ntfy-godeep-automation.sh L15-L28

The script runs an infinite loop that subscribes to the ntfy topic and processes each notification:

Sources: scripts/ntfy-godeep-automation.sh L39-L151

The script uses pattern matching to identify GitHub installation notifications:

if echo "$title" | grep -q "GitHub Connected\|GitHub Installation"; then

This regex matches notification titles from the OAuth callback handler (app/api/auth/github/callback/route.ts L87-L93

). When matched, the script enters the installation processing workflow.

Sources: scripts/ntfy-godeep-automation.sh L49

The installation ID is extracted from the notification message using grep with regex:

installation_id=$(echo "$message" | grep -o 'Installation ID: [0-9]*' | grep -o '[0-9]*$')

This extraction targets the message format: "Installation ID: <number>" which is sent by the callback handler.

Sources: scripts/ntfy-godeep-automation.sh L53

The script calls the admin token generation API with the extracted installation ID:

API Request Structure

The curl command constructs a POST request:

response=$(curl -s -X POST "$ADMIN_URL" \    -H "Content-Type: application/json" \    -d "{\"installationId\":\"$installation_id\",\"password\":\"$ADMIN_PASSWORD\"}")

Sources: scripts/ntfy-godeep-automation.sh L62-L65

The script extracts four key fields from the API response using jq:

Fieldjq ExpressionFallback
Access token.tokenempty
Repository full name.repositories[0].full_nameempty
Repository name.repositories[0].nameempty
Customer email.user.email // .user.usernameempty

The fallback chain for customer identification (email // .user.username) ensures the script can handle cases where email is not available.

Sources: scripts/ntfy-godeep-automation.sh L68-L71

The script generates a formatted repository name that includes the customer identifier:

email_prefix=$(echo "$customer_email" | sed 's/@/_/g; s/\./_/g' | tr '[:upper:]' '[:lower:]')formatted_repo_name="${email_prefix}-${repo_name}"

This transformation:

  1. Replaces @ symbols with underscores
  2. Replaces . symbols with underscores
  3. Converts to lowercase
  4. Concatenates with the original repository name

Example: john.doe@example.com + my-repo → john_doe_example_com-my-repo

Sources: scripts/ntfy-godeep-automation.sh L79-L84

The script clones the customer's repository using token authentication:

git clone "https://x-access-token:${token}@github.com/${repo_full_name}.git" "$clone_path"

The x-access-token authentication scheme is GitHub's standard method for using personal access tokens or installation access tokens with HTTPS git operations.

Sources: scripts/ntfy-godeep-automation.sh L90

After successful cloning, the script creates a clean repository with a new commit history:

Re-initialization Steps

This process ensures that:

  1. The customer's commit history is not retained
  2. The owner's private repository has a single, clean commit
  3. The customer email is documented in the commit message for tracking

Sources: scripts/ntfy-godeep-automation.sh L99-L103

The script uses the GitHub CLI (gh) to create a private repository and push the re-initialized code:

gh repo create "klaudioz/$formatted_repo_name" --private --source=. --push

This single command:

  1. Creates a new private repository in the klaudioz account
  2. Adds it as a remote to the local repository
  3. Pushes all commits to the new remote

Repository Creation Flow

Sources: scripts/ntfy-godeep-automation.sh L106

After successful or failed repository creation, the script deletes the local clone to conserve disk space:

cd - > /dev/nullrm -rf "$clone_path"

The cd - command returns to the previous directory before deletion, preventing the script from attempting to delete the current working directory.

The cleanup happens in both success and failure paths:

This ensures disk space is freed regardless of outcome.

Sources: scripts/ntfy-godeep-automation.sh L110-L127

The scripts use AppleScript via osascript to display native macOS notifications at each stage of processing.

StageNotification ContentCode Location
Installation detected"Processing Installation ID: {id}"scripts/ntfy-godeep-automation.sh L59
Clone complete"Repository cloned to {path}"scripts/ntfy-godeep-automation.sh L94
Repo created successfully"Repository created: klaudioz/{name}"scripts/ntfy-godeep-automation.sh L117
Repo creation failed"Failed to create repo: {name}"scripts/ntfy-godeep-automation.sh L129
Clone failed"Clone failed for {repo}"scripts/ntfy-godeep-automation.sh L134
Token generation failed"Failed to process Installation ID: {id}"scripts/ntfy-godeep-automation.sh L139
Other notifications"{message}" with title "{title}"scripts/ntfy-godeep-automation.sh L147

All notifications use the same AppleScript pattern:

osascript -e "display notification \"<message>\" with title \"<title>\""

The -e flag allows inline AppleScript execution without requiring a separate file.

Sources: scripts/ntfy-godeep-automation.sh L59-L147

The script implements several validation checkpoints throughout execution:

Error Detection Points

The script distinguishes between fatal errors (exit immediately) and non-fatal errors (log and continue):

Fatal Errors (exit script):

Non-Fatal Errors (log and continue to next notification):

Non-fatal errors allow the script to continue processing future notifications even if one customer's installation fails.

Sources: scripts/ntfy-godeep-automation.sh L17-L143

The script requires the following command-line tools:

ToolPurposeInstallation Check
ntfySubscribe to ntfy.sh topicswhich ntfy
jqParse JSON responseswhich jq
gitClone repositorieswhich git
ghGitHub CLI for repo creationwhich gh
curlHTTP requests to admin APIwhich curl
osascriptmacOS notificationsBuilt into macOS

The script expects a .env file in the project root containing:

ADMIN_PASSWORD=<your-admin-password>

This password must match the ADMIN_PASSWORD environment variable configured in the Vercel deployment.

Sources: scripts/README.md L9-L80

Run the script in the foreground to see real-time output:

./scripts/ntfy-godeep-automation.sh

Stop with Ctrl+C.

Run the script as a background process with logging:

nohup ./scripts/ntfy-godeep-automation.sh > ~/ntfy-godeep.log 2>&1 &

This command:

  • nohup: Prevents termination when terminal closes
  • > ~/ntfy-godeep.log: Redirects stdout to log file
  • 2>&1: Redirects stderr to stdout (same log file)
  • &: Runs in background
TaskCommand
Stop background scriptpkill -f ntfy-godeep-automation
View logstail -f ~/ntfy-godeep.log
Check if runningps aux | grep ntfy-godeep-automation

Sources: scripts/README.md L15-L63

Authentication Failures

Symptom: API returns 401 or token validation fails

Causes:

  • Password mismatch between .env and Vercel environment variables
  • API endpoint not deployed with latest changes

Resolution:

  1. Verify .env password matches Vercel ADMIN_PASSWORD
  2. Check Vercel deployment logs for API errors

Clone Failures

Symptom: git clone command fails

Causes:

  • Token expired (1-hour GitHub limitation)
  • Network connectivity issues
  • GitHub App permissions incorrect

Resolution:

  1. Check token generation timestamp in logs
  2. Verify network connectivity to GitHub
  3. Verify GitHub App has "Contents: Read-only" permission

Script Won't Start

Symptom: Script exits immediately after launch

Causes:

  • .env file not found
  • ADMIN_PASSWORD not set in .env
  • Required tools not installed

Resolution:

  1. Verify .env exists in project root
  2. Check ADMIN_PASSWORD is defined in .env
  3. Run which ntfy, which jq, which gh to verify tool installation

Sources: scripts/README.md L65-L80

The complete automation workflow from notification to repository creation:

This workflow executes automatically for each GitHub installation notification, requiring no manual intervention from the owner until the manual documentation generation step.

Sources: scripts/ntfy-godeep-automation.sh L39-L151

scripts/README.md L36-L51

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

05.c - Automation-Scripts | DeepWiki | godeep.wiki